home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / src / exampleCode / opengl / utilities / isfast / libtk / README < prev    next >
Encoding:
Text File  |  1994-08-02  |  9.7 KB  |  323 lines
  1. /*
  2. ** Nano Window Toolkit.
  3. ** Version 1.0
  4. */
  5.  
  6.  
  7. /*
  8. ** Windowing functions.
  9. */
  10.  
  11. void tkInitDisplayMode(GLenum type);
  12.     - Preset window type.
  13.     - GLenum type:
  14.     TK_RGB or TK_INDEX
  15.     TK_SINGLE or TK_DOUBLE
  16.     TK_DIRECT or TK_INDIRECT
  17.     TK_ACCUM
  18.     TK_ALPHA
  19.     TK_DEPTH
  20.     TK_OVERLAY
  21.     TK_UNDERLAY
  22.     TK_STENCIL
  23.     
  24. void tkInitPosition(int x, int y, int w, int h);
  25.     - Preset window size and top-left corner location.
  26.  
  27. GLenum tkInitWindow(char *titleStr);
  28.     - Create new window.
  29.  
  30.     Use tkInitDisplay to set values determining whether the window 
  31.     requested will be RGB or COLOR_INDEX and what buffer structure you want 
  32.     the window to have.  
  33.         You may request buffers and modes for the window by or'ing the values 
  34.     listed below into the 'type'.  tkInitPosition will similarly set 
  35.     the position and size of the window.  
  36.         The properties set by these functions will be used by 
  37.     tkInitWindow when the window is created. If the window cannot be created 
  38.     with the requested buffers, tkInitWindow prints an diagnostic message and 
  39.     exits.
  40.  
  41. void tkCloseWindow(void);
  42.     - Close window.
  43.  
  44. void tkQuit(void);
  45.     - Quit application.
  46.  
  47.     tkClose window frees the memory used by some of the tk routines,
  48.     calls glFinish, sets the event functions to null, and gets rid of the 
  49.     window.  tkQuit calls tkCloseWindow and exits the current program.
  50.  
  51. GLenum tkSetWindowLevel(GLenum level);
  52.     - Set drawing plane of window.
  53.     - GLenum level:
  54.     TK_RGB or TK_INDEX
  55.     TK_OVERLAY
  56.     TK_UNDERLAY
  57.  
  58.  
  59.     If the window was created with an overlay plane this redirects the
  60.     rendering to the appropriate plane.  TK_UNDERLAY is currently
  61.     not used.  
  62.  
  63.  
  64.  
  65. void tkSwapBuffers(void);
  66.     - Swap draw/view buffer in double buffered window.
  67.  
  68.     If the window supports double-buffering this makes the contents
  69.     of the back buffer visible, performing an implicit glFlush().
  70.     The contents of the back buffer are undefined after this call.
  71.  
  72.  
  73.  
  74. /*
  75. ** Event functions.
  76. */
  77.  
  78.     The user may want to create an Expose, a Reshape, and a Display 
  79.     callback function for use by the tk event structure. Some of these 
  80.     events may correspond to window system events, and others are input
  81.     events. The event loop code can be better understood by looking
  82.     at the tkExec function in the file 'event.c'. The functions below
  83.     are used to set the various callback functions.
  84.  
  85. void tkExposeFunc(void (*Func)(int w, int h));
  86.     - Set window expose callback routine.
  87.     - void (*Func)(int w, int h)
  88.     - Callback routine will receive window size at window expose time.
  89.  
  90. void tkReshapeFunc(void (*Func)(int w, int h));
  91.     - Set window reshape callback routine.
  92.     - void (*Func)(int w, int h)
  93.     - Callback routine will receive window size after window reshape.
  94.  
  95. void tkDisplayFunc(void (*Func)(void));
  96.     - Set display callback routine.
  97.     - In general this should do *most* of the drawing. It should draw the
  98.     entire screen.
  99.  
  100. void tkKeyDownFunc(GLenum (*Func)(int key, GLenum states));
  101.     - Set key event callback routine.
  102.     - void (*Func)(int key, GLenum states)
  103.     - Callback routine will receive key pressed and state of the
  104.       shift and control keys.
  105.     - Callback routine will return GL_TRUE if the display callback
  106.       routine should be called or GL_FALSE if the display callback
  107.       should not be called.
  108.     - int key:
  109.         TK_ESCAPE
  110.         TK_LEFT TK_UP TK_RIGHT TK_DOWN
  111.         TK_RETURN
  112.         TK_SPACE
  113.         TK_A through TK_Z
  114.         TK_a through TK_z
  115.         TK_0 through TK_9
  116.     - GLenum states:
  117.         TK_SHIFT
  118.         TK_CONTROL
  119.  
  120. void tkMouseDownFunc(GLenum (*Func)(int x, int y, GLenum states));
  121.     - Set mouse button down event callback routine.
  122.     - void (*Func)(int x, int y, GLenum states)
  123.     - Callback routine will receive mouse x, y location and button states
  124.       when the mouse button down event occurred.
  125.     - Callback routine will return GL_TRUE if the display callback
  126.       routine should be called or GL_FALSE if the display callback
  127.       should not be called.
  128.     - GLenum states:
  129.         TK_LEFTBUTTON
  130.         TK_RIGHTBUTTON
  131.         TK_MIDDLEBUTTON
  132.  
  133. void tkMouseUpFunc(GLenum (*Func)(int x, int y, GLenum states));
  134.     - Set mouse button up event callback routine.
  135.     - void (*Func)(int x, int y, GLenum states)
  136.     - Callback routine will receive mouse x, y location and button states
  137.       when the mouse button up event occurred.
  138.     - Callback routine will return GL_TRUE if the display callback
  139.       routine should be called or GL_FALSE if the display callback
  140.       should not be called.
  141.     - GLenum states:
  142.         TK_LEFTBUTTON
  143.         TK_RIGHTBUTTON
  144.         TK_MIDDLEBUTTON
  145.  
  146. void tkMouseMoveFunc(GLenum (*Func)(int x, int y, GLenum states));
  147.     - Set mouse move event callback routine.
  148.     - void (*Func)(int x, int y, GLenum states)
  149.     - Callback routine will receive mouse x, y location and button states
  150.       when the mouse move event occurred.
  151.     - Callback routine will return GL_TRUE if the display callback
  152.       routine should be called or GL_FALSE if the display callback
  153.       should not be called.
  154.     - GLenum states:
  155.         TK_LEFTBUTTON
  156.         TK_RIGHTBUTTON
  157.         TK_MIDDLEBUTTON
  158.  
  159. void tkIdleFunc(void (*Func)(void));
  160.     - Set idle event callback routine.
  161.     - Idle is for when the there are no events.
  162.  
  163.  
  164. void tkExec(void)
  165.     - Pass control to tk's event handling code. See file event.c for
  166.       exact flow control algorithm.
  167.  
  168. /*
  169. ** Get functions.
  170. */
  171.  
  172.  
  173. int tkGetColorMapSize(void);
  174.     - return size of color map.
  175.  
  176. void tkGetMouseLoc(int *x, int *y);
  177.     - return current mouse x, y location.
  178.  
  179. Display *tkGetXDisplay(void);
  180.     - return X windowing system display. (note: Windowing system specific)
  181.  
  182. Window tkGetXWindow(void);
  183.     - return X windowing system window.  (note; Windowing system specific)
  184.  
  185. /*
  186. ** Set functions.
  187. */
  188.     These functions set color maps for use by the windowing system.
  189.  
  190. void tkSetOneColor(int ci, float r, float g, float b);
  191.     - Set color index to the r, g, b values.
  192.  
  193. void tkSetFogRamp(int density, int size);
  194.     - Set up a fog ramp in the color map starting at entry 0 and of length
  195.       2^size.
  196.  
  197. void tkSetGreyRamp(void);
  198.     - Set the entire color map to a grey scale ramp.
  199.  
  200. void tkSetRGBMap(int size, float *rgb);
  201.     - Set up the main window's color map. The rgb values are in the form
  202.       r[size] followed by g[size] followed by b[size].
  203.  
  204. void tkSetOverlayMap(int, float *);
  205.     - Set up the overlay plane's color map. The rgb values are in the form
  206.       r[size] followed by g[size] followed by b[size].
  207.  
  208. /*
  209. ** Cursor functions.
  210. */
  211.  
  212. void tkNewCursor(GLint id, GLubyte *shape, GLubyte *mask, GLenum fgColor,
  213.          GLenum bgColor, GLint hotX, GLint hotY)
  214.     - Define and initialize a cursor.
  215.     - GLenum fgColor, bgColor:
  216.     TK_BLACK
  217.     TK_RED
  218.     TK_GREEN
  219.     TK_YELLOW
  220.     TK_BLUE
  221.     TK_MAGENTA
  222.     TK_CYAN
  223.     TK_WHITE
  224.  
  225. void tkSetCursor(GLint id);
  226.     - Make cursor active.
  227.  
  228. /*
  229. ** RGB image function.
  230. */
  231.     This is used to read an RGB file into a program. The file's structure
  232.     can be inferred from the structure at the top of the image.c file. This
  233.     is the type of file created by the 'snap' routine.
  234.  
  235. TK_RGBImageRec *tkRGBImageLoad(char *fileName);
  236.     - Creates an RGB image from a .rgb file.
  237.     - typedef struct _TK_RGBImageRec {
  238.     GLint sizeX, sizeY;
  239.     unsigned char *data;
  240.       } TK_RGBImageRec;
  241.     - Image of sizeX and sizeY. Eight bit data is in the form r0, g0, b0,
  242.       r1, g1, b1, r2, g2, b2, ...
  243.  
  244. /*
  245. ** Simple font function.
  246. */
  247.     Display lists, which render a stroke font, an outline font, 
  248.     a filled font, or a bitmap font, can be created by the functions 
  249.     listed below.
  250.  
  251. GLenum tkCreateStrokeFont(GLuint base);
  252.     - Creates a stroke font display list starting at given base.
  253.  
  254. GLenum tkCreateOutlineFont(GLuint base);
  255.     - Creates an outline font display list starting at given base.
  256.  
  257. GLenum tkCreateFilledFont(GLuint base);
  258.     - Creates a filled font display list starting at given base.
  259.  
  260. GLenum tkCreateBitmapFont(GLuint base);
  261.     - Creates a bitmap font display list starting at given base.
  262.  
  263. void tkDrawStr(GLuint base, char *str);
  264.     - draws string in the font specified by the given display list base.
  265.  
  266. /*
  267. ** Simple object function.
  268. */
  269.  
  270. void tkWireSphere(GLuint base, float radius);
  271. void tkSolidSphere(GLuint base, float radius);
  272. void tkWireCube(GLuint base, float size);
  273. void tkSolidCube(GLuint base, float size);
  274. void tkWireBox(GLuint base, float width, float height, float depth);
  275. void tkSolidBox(GLuint base, float width, float height, float depth);
  276. void tkWireTorus(GLuint base, float innerRadius, float outerRadius);
  277. void tkSolidTorus(GLuint base, float innerRadius, float outerRadius);
  278. void tkWireCylinder(GLuint base, float radius, float height);
  279. void tkSolidCylinder(GLuint base, float radius, float height);
  280. void tkWireCone(GLuint base, float b, float h);
  281. void tkSolidCone(GLuint base, float b, float h);
  282.     - Creates various display list shapes starting at the given base.
  283.  
  284. /* 
  285. ** Helpful window mask tests.
  286. */
  287.  
  288. #define TK_IS_RGB(x)        (((x) & TK_INDEX) == 0)
  289. #define TK_IS_INDEX(x)        (((x) & TK_INDEX) != 0)
  290. #define TK_IS_SINGLE(x)        (((x) & TK_DOUBLE) == 0)
  291. #define TK_IS_DOUBLE(x)        (((x) & TK_DOUBLE) != 0)
  292. #define TK_IS_DIRECT(x)        (((x) & TK_INDIRECT) != 0)
  293. #define TK_IS_INDIRECT(x)    (((x) & TK_INDIRECT) == 0)
  294. #define TK_HAS_ACCUM(x)        (((x) & TK_ACCUM) != 0)
  295. #define TK_HAS_ALPHA(x)        (((x) & TK_ALPHA) != 0)
  296. #define TK_HAS_DEPTH(x)        (((x) & TK_DEPTH) != 0)
  297. #define TK_HAS_OVERLAY(x)    (((x) & TK_OVERLAY) != 0)
  298. #define TK_HAS_UNDERLAY(x)    (((x) & TK_UNDERLAY) != 0)
  299. #define TK_HAS_STENCIL(x)    (((x) & TK_STENCIL) != 0)
  300.  
  301. /*
  302. ** Helpful color macro.
  303. */
  304.  
  305. #define TK_SETCOLOR(windType, color) (TK_IS_RGB((windType)) ? \
  306.                      glColor3fv(tkRGBMap[(color)]) : \
  307.                      glIndexf((color)))
  308.     - GLenum windType:
  309.     TK_RGB or TK_INDEX
  310.     - GLenum color:
  311.     TK_BLACK
  312.     TK_RED
  313.     TK_GREEN
  314.     TK_YELLOW
  315.     TK_BLUE
  316.     TK_MAGENTA
  317.     TK_CYAN
  318.     TK_WHITE
  319.  
  320. known bugs: The x implementations of this does not set some of the 
  321. x-properties.  There is a lot of potential for name-space collisions.  
  322. (This library uses the terms 'xDisplay', 'xScreen', and 'w' to name a few.
  323.